Command Templates

Command Templates are run-time templates that actively pass commands to a list of specified devices during their runtime. After all responses are collected, the output set is evaluated against a set of defined rules. These executed templates are referred to as Pre and Post steps, which are typically separated by a procedure (router upgrade, service migration, etc.).

Prerequisites

At this time, no prerequisites are required.

Using Command Templates

With the Command Template designer, you can execute commands on physical devices to see the actual response and rules evaluation.

1. Navigate to IAP → Automation Studio → Command Templates.

2. Click the plus (+) icon in the top menu to create a new template. The Create dialog opens.

   

3. Select Command Template from the dropdown menu. Next, enter a template name.

4. Click Create. The Command Template form displays.

   

5. Enter the device name in the search field (upper right) to select a device.

   

6. Add the relevant command variables and rules. For more information, see the sections on Command Template Variables and Defining Command Template Rules below.

   • Click Add Command to add a new command.
   • Click Add Rule to add a new rule to a command.
   • Click the trashcan icon next to either a rule or command to delete.

   
   

   

7. Click Test This Command for a single command or Test All Commands to test all the commands at once. After evaluating the test output, rules will be marked with either a green check mark (passed) or red minus sign (failed) . The device response will appear at the bottom of the screen in the Test results.

   

Defining Command Templates

Command Templates contain sets of commands with associated rules, including flags to define rules logic.

Global Command Pass

At the top of the template is a dropdown menu (All Commands must pass/ One Command must pass) that works the same as setting the individual pass flags on each command, except on a global level.

• All commands must pass (default behavior): Pass for every rule in every command.
• All commands must pass (warn/info as pass checked): Zero errors errors present in the template.
• One command must pass (default behavior): Pass for all rules in ONE (or more) commands.
• One command must pass (warn/info as pass checked): One command with zero errors must be present in the template.

There is also a pass checkbox (optional) to ignore failures due to warning or info severity levels. The default for the global pass checkbox is "off'.

Rules

The following options are available in the Rules dropdown for all Command Templates. For more information, see the sections on Command Template Variables and Defining Command Template Rules below.

Option	Description
contains	Will verify a specified string exists in the device response.
!contains	Will verify a specified string does not exist in the device response.
contains1	Will verify a specified string exists only once in the device response.
RegEx	Will verify a regular expression matches the device response.
!RegEx	Will verify a regular expression does not match the device response.
#comparison	Compares two values, both of which may be extracted from the device response.

Flags

Every command may have one or more rules which are bound by a boolean Flag called a "pass flag".

• When a pass flag is set to true (on), the logic between the rules is "AND". This means all rules must pass in order for the command to pass.
• When a pass flag is set to false (off), the logic is "OR". This means that only one rule has to pass for the command to pass.

The following flags are supported.

Flag	Description
i	Ignore case. Make the whole expression case-insensitive.
g	Global search. Retain the index of the last match, allowing iterative searches.
m	Multi-line. Beginning/end anchors (^/$) will match the start/end of a line.

Of note, the contains option only has one flag option: i.

The RegEx and comparison options have all three flag options: i, g, and m.

Severity

A Severity field is available for each rule. The severity only applies to a rule after it has failed. The default severity is error.

Level	Description
error	Something is wrong or is not behaving normally, and a specific action may need to be taken.
warning	There is something to be aware of that could potentially cause a problem.
info	Informational messages have been logged.

Global Rules Pass

For each command there is a dropdown (All Rules must pass/ One Rule must pass) that works the same as setting rules on each command, except on a global level.

• All Rules must pass: Pass for every rule in a command.
• One Rule must pass: Pass for one rule (or more) in a command.

Command Template Variables

When defining Command Templates, variables may be used in the commands with the following syntax:

<!VARIABLE!>

The following variable types can be used when defining commands:

• string
• number
• boolean
• array of strings
• array of numbers
• array of booleans

When arrays of simple types are passed into the execution engine, the command will be executed one time for each element in the array. Complex variable structures such as arrays of complex objects are not currently supported.

Defining Command Template Rules

The contains and RegEx operators search for command output matching (or not matching) a given string or regular expression. The #comparison operator evaluates the values in returned data.

Rule Type	Match Type to Device Response	Output	Supported Flag
contains	String	True if the device response contains the requested value.	Ignore case (i)
!contains	String	True if the device response does not contain the requested value.	Ignore case (i)
contains1	String	True if the device response contains 1 and only 1 occurence of the requested value.	Ignore case (i)
RegEx	Regular expression comparison.	True if the device response matches the requested regex pattern.	Ignore case (i) Global search (g) Multi-line (m)
#comparison	Comparison against two values, both of which may be extracted from the device response.	The #comparison rule type defines its own set of Operands (Top and Bottom) and a Comparison Operator. See below for more information.

Top Comparison Operands

• Uses a regular expression with a capture group to select data in the output of a command. The regular expression must be surrounded with slash (/) characters.
• The expression serves two functions: it identifies the command output location (where we will find the top comparison operand value) and returns the comparison operand value.
• Capture groups are created by surrounding the relevant part of the regular expression with round brackets or parentheses. A single capture group is supported.

Bottom Comparison Operands

• Will specify a static value, a passed MOP command template variable, or a second regular expression and capture group matching part of the command's output.

Comparison Operators

Comparison operators compare values and return true or false.

Operator	Comparison Type	Description
=	String	Returns true if the top and bottom string comparison operands are equal; otherwise returns false.
!=	String	Returns true if the top and bottom string comparison operands are not equal; otherwise returns false.
<=	Number	Returns true if the top number comparison operand is equal to or less than the bottom number comparison operand; otherwise returns false.
<	Number	Returns true if the top number comparison operand is less than the bottom number comparison operand; otherwise returns false.
>=	Number	Performs a number comparison. Returns true if the top number comparison operand is greater than or equal to the bottom number comparison operand; otherwise returns false.
>	Number	Returns true if the top number comparison operand is greater than the bottom number comparison operand; otherwise returns false.
%	Number	Evaluates a percentage value calculation against a threshold. The percentage value is calculated by multiplying 100 times the bottom number comparison operand divided by the top number comparison operand: 100 x (bottom comparison operand / top comparison operand) . The threshold is a static number typed in the Max accepted % field. Returns true if the percentage value is less than or equal to the threshold; otherwise it returns false.

Configuration Examples

Use the following examples to configure various rules and comparison operators and operands for a Command Template.

Example 1

In this example, we need to verify Cisco CSR has sufficient memory. The IOS command show platform software vmemory info prints memory statistics, including the total system memory.

In the application:

1. Create a new Command Template.
2. Select a device name for testing.
3. Type show platform software vmemory info in the command field of Command #1.
4. Keep the default contains operator.
5. Click Test This Command.
6. The test results will display.

Example Test Results

Memory Upgrade Limits:
    Total System Memory:        3890 MB
    Memory From Upgrade Licenses:   0 MB
    Memory From Feature Licenses:   0 MB
Memory Available For Upgrade:
    Available System Memory:    0 MB
    Available Upgrade Licensed Memory:  0 MB
    Available Feature Licensed Memory:  0 MB
Current Memory Allocation:
    IOSD:   2354 MB (default) + 0 MB upgrade
    Data Plane: 1536 MB (default) + 0 MB upgrade

Top Comparison Operand

To build a regular expression to select data:

1. Select RegEx operator.
2. Type a regular expression to select the command's output data containing the first operand. The line containing "Total System Memory" includes the first operand, 3890 MB.
3. Type Total System Memory:\s+\d+ MB in the rule field.
4. Click Test This Command.
5. Verify a green check is displayed, indicating the rule matches.
6. If a red dash is displayed, check the regular expression for errors.

To build a capture group:

1. Change the command operator to #comparison.
2. Surround the regular expression rule with slash characters:

   /Total System Memory:\s+\d+ MB/

1. Add a capture group by placing a pair of parentheses around the part of our regular expression matching installed memory:

   /Total System Memory:\s+(\d+) MB/

To set the comparison operator:

1. Select >= comparison operator.

Bottom Comparison Operand

To define a comparison using a Bottom Operand:

1. Type 3000 in the compare with field.
2. Click Test This Command.
3. Verify a green check is displayed, indicating the rule matches.
4. If a red dash is displayed, check the top comparison operand regular expression for errors.

Example 2

This example extends the previous example; we need to verify Cisco CSR has sufficient memory. In the previous example, we compared installed memory to a static value. In this example, we compare installed memory to a variable.

Variable MEM-THRESH will be passed to the MOP command template.

Bottom Comparison Operand

• Type <!MEM-THRESH!> in the Compare with field.

Example 3

In this example, we have an EBGP adjacency configured with a maximum prefix of 10 prefixes. The adjacency is configured to log warning messages when the neighbor sends 80% or more of the maximum number of prefixes, and the adjacency is reset if the neighbor sends more than 10 prefixes. In this example, we verify the number of sent prefixes is not greater than the warning threshold.

The IOS command show ip bgp neighbor X.X.X.X prints the number of accepted prefixes, the maximum prefix limit, and the warning threshold.

1. In the application, create a new command template.

2. Select a device name for testing.

3. Type show ip bgp neighbor X.X.X.X in the command field for Command 1.

   • Replace X.X.X.X with a valid EBGP neighbor's router ID.

4. Keep the default contains operator.

5. Click Test This Command.

6. The test results will display.

   Router_B#show ip bgp neighbor 10.0.0.1
   BGP neighbor is 10.0.0.1,  remote AS 200, external link
   BGP version 4, remote router ID 10.0.0.1
   BGP state = Established, up for 00:13:22
   Last read 00:00:21, hold time is 180, keepalive interval is 60 seconds
   Neighbor capabilities:
       Route refresh: advertised and received(old & new)
       Address family IPv4 Unicast: advertised and received
       IPv4 MPLS Label capability:
   Received 930 messages, 0 notifications, 0 in queue
   Sent 919 messages, 1 notifications, 0 in queue
   Default minimum time between advertisement runs is 30 seconds

   For address family: IPv4 Unicast
   BGP table version 30, neighbor version 30
   Index 1, Offset 0, Mask 0x2
   Route refresh request: received 0, sent 0
   9 accepted prefixes consume 432 bytes
   Prefix advertised 0, suppressed 0, withdrawn 0, maximum limit 10 (warning-only
   )
   Threshold for warning message 80%

   Connections established 2; dropped 1
   Last reset 00:29:13, due to BGP Notification sent, update malformed
   Message received that caused BGP to send a Notification:
       FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF
       003C0200 00001940 01010040 02040201
       00C84003 040A0000 01800404 00000000
       180A000A 180A000B 180A000C
   External BGP neighbor can be up to 2 hops away.
   Connection state is ESTAB, I/O status: 1, unread input bytes: 0
   Local host: 10.0.0.2, Local port: 15668
   Foreign host: 10.0.0.1, Foreign port: 179

   Enqueued packets for retransmit: 0, input: 0  mis-ordered: 0 (0 bytes)

   Event Timers (current time is 0x3A46EB54):
   Timer          Starts    Wakeups            Next
   Retrans            18          0             0x0
   TimeWait            0          0             0x0
   AckHold            22          9             0x0
   SendWnd             0          0             0x0
   KeepAlive           0          0             0x0
   GiveUp              0          0             0x0
   PmtuAger            0          0             0x0
   DeadWait            0          0             0x0

   iss: 2047376434  snduna: 2047376784  sndnxt: 2047376784     sndwnd:  16035
   irs:  821061364  rcvnxt:  821062116  rcvwnd:      16188  delrcvwnd:    196

   SRTT: 279 ms, RTTO: 500 ms, RTV: 221 ms, KRTT: 0 ms
   minRTT: 24 ms, maxRTT: 384 ms, ACK hold: 200 ms
   Flags: higher precedence, nagle

   Datagrams (max data segment is 536 bytes):
   Rcvd: 33 (out of order: 0), with data: 22, total data bytes: 751
   Sent: 29 (retransmit: 0, fastretransmit: 0), with data: 17, total data bytes: 349

1. Select the #comparison operator.
2. Type /maximum limit\s(\d+)/ in the Rule field.
3. Select the %comparison operator.
4. Type 80 in the Max accepted % field.
5. Type /(\d+) accepted prefixes/ in the Compare with field.

Using the Command Template Controls

The easiest way to import, export and delete a Command Template is to use the controls from the Command Templates collection page. From the Automation Studio welcome page, click the Search button and the Collection dialog will open.

From this page view, you can Import, Export or Delete command templates by using the controls located in the toolbar at the top of the canvas.

Note: The Export and Delete icons are grayed out (disabled) until the radio button (bottom left circle) of a template card is checked.

Controls Toolbar

A description of each control icon is provided in the reference table that follows.

UI Action	Description	Icon
Refresh	Refreshes the Command Templates view in the current window.
Import	Imports a template.
Select All	Selects all templates in the current window.
Delete	Deletes the template when the radio button is selected.
Export	Exports the template when the radio button is selected.

To Export or Delete a template in the list, select the desired template by checking the circle in the lower left corner of the template card, and then click the appropriate icon. Alternately, you can hover over the vertical three dot icon in the lower right corner of a template card to open a menu of options for that specific template, namely Edit, Clone (create a copy), Delete or Export.

You can open any template by clicking the name (in blue) at the top of the card. When a template is open, a new template can be Imported using the icon located in the top toolbar on the left. Additional options to View metadata, Clone, Revert changes, Export or Delete the open template can be found by clicking the three dot menu icon found in the top right corner.

Import a Command Template

Clicking the Import icon opens the Import dialog. Select Command Template from the dropdown list and then use the search bar to locate the desired template file for import. Once the file is selected for upload, click Import.

Export a Command Template

Clicking the Export icon will open a dialog box with the options to open the template file or save it to a specific location.

Delete a Command Template

After clicking the Delete icon, a confirmation box pops up and prompts the user to confirm the delete action. Once a template is deleted, it cannot be undone. It will no longer show in the Command Templates collection view.

Click OK to confirm the deletion.